# Copyright (c) 2022-2025, The Isaac Lab Project Developers.
# All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause

from isaaclab.utils import configclass

from isaaclab_rl.rsl_rl import RslRlOnPolicyRunnerCfg, RslRlPpoActorCriticCfg, RslRlPpoAlgorithmCfg

"""
    参数调整建议：

        如果训练不稳定: 尝试减小学习率(learning_rate)或增大num_mini_batches

        如果收敛速度慢: 适当增大num_steps_per_env或调整网络结构

        如果探索不足: 增加entropy_coef或init_noise_std

        如果过拟合：可以尝试添加正则化或减小网络维度

    网络设计：
      逐步压缩原则：

        层维度递减(256 → 128 → 64)是深度学习中的常见模式

        前层捕捉高级特征，后层提取决策关键信息

        类似图像网络中CNN的通道数变化逻辑

      平衡容量与效率：

        首层较大(256)可捕捉复杂状态表征

        逐渐缩小防止过拟合，提升计算效率

      任务适配性：

        机械臂控制需要处理连续状态/动作空间

        相对复杂任务需要中等规模网络(3层)
"""

@configclass
class PPORunnerCfg(RslRlOnPolicyRunnerCfg):
    num_steps_per_env = 24                # 每个环境每次迭代采集的步数  控制每次迭代从每个环境收集的经验步数 影响每次迭代的样本量，值越大训练越稳定但内存消耗越多
    max_iterations = 1500                  # 最大训练迭代次数
    save_interval = 50                    # 每隔多少次迭代保存模型
    experiment_name = "franka_lift"   # 实验名称（用于保存结果）
    empirical_normalization = False       # 是否使用经验归一化
    policy = RslRlPpoActorCriticCfg(  # 策略网络配置（Actor-Critic）
        init_noise_std=1.0,               # 初始动作噪声标准差    初始探索噪声，随着训练会自动衰减
        actor_hidden_dims=[256, 128, 64],       # Actor网络隐藏层维度
        critic_hidden_dims=[256, 128, 64],      # Critic网络隐藏层维度
        activation="elu",                 # 激活函数类型（Exponential Linear Unit）激活函数选择，ELU可以缓解梯度消失问题 比ReLU更平滑，缓解Dead Neurons问题，适合连续控制任务
    )
    algorithm = RslRlPpoAlgorithmCfg(
        value_loss_coef=1.0,              # 价值函数损失系数
        use_clipped_value_loss=True,      # 是否使用截断的价值损失
        clip_param=0.2,                   # PPO的clip参数（ϵ）      限制策略更新的幅度，防止过大的策略更新
        entropy_coef=0.006,               # 熵奖励系数              控制探索强度，值越大鼓励更多随机动作
        num_learning_epochs=5,            # 每次迭代的优化轮次         每次迭代重复使用数据优化的次数
        num_mini_batches=4,               # 小批量(mini-batch)的数量  将数据分成多少个小批量进行优化
        learning_rate=1.0e-4,             # 学习率
        schedule="adaptive",              # 学习率调整策略（自适应）     根据KL散度自动调整学习率
        gamma=0.98,                       # 折扣因子                未来奖励的折扣因子，接近1表示更重视长期回报
        lam=0.95,                         # GAE的λ参数              GAE参数，平衡偏差与方差
        desired_kl=0.01,                  # 目标KL散度值（用于自适应调整）   目标KL散度值，用于判断是否需要调整学习率
        max_grad_norm=1.0,                # 梯度裁剪的最大范数     梯度裁剪，防止梯度爆炸
    )